Frontend WebHID Apparaatfilter: Selectie van Human Interface Devices Uitgelegd

De WebHID API opent een wereld van mogelijkheden voor webapplicaties, waardoor ze rechtstreeks kunnen communiceren met Human Interface Devices (HID's) zoals gamepads, gespecialiseerde invoerapparaten en meer. Een cruciaal onderdeel van het effectief gebruiken van WebHID is het begrijpen van apparaatfilters. Deze uitgebreide gids leidt u door de ins en outs van WebHID-apparaatfilters, zodat u krachtige en boeiende webervaringen kunt creëren.

Wat is WebHID?

WebHID is een web-API die webapplicaties in staat stelt te communiceren met HID-apparaten die zijn aangesloten op de computer of het mobiele apparaat van een gebruiker. In tegenstelling tot traditionele web-API's die afhankelijk zijn van specifieke apparaatstuurprogramma's, biedt WebHID een generieke interface voor interactie met een breed scala aan apparaten, zolang de gebruiker toestemming geeft. Dit maakt het ideaal voor apparaten die geen native browserondersteuning hebben of aangepaste invoer-afhandeling vereisen.

Waarom WebHID gebruiken?

• Directe Toegang tot Apparaten: Communiceer rechtstreeks met HID-apparaten zonder afhankelijk te zijn van browserspecifieke stuurprogramma's.
• Aangepaste Invoer-afhandeling: Implementeer aangepaste invoertoewijzing en -verwerking voor gespecialiseerde apparaten.
• Brede Apparaatondersteuning: Ondersteun een breder scala aan apparaten, waaronder gamepads, wetenschappelijke instrumenten en industriële controllers.
• Verbeterde Gebruikerservaring: Creëer meeslepende en interactieve webervaringen.

WebHID Apparaatfilters Begrijpen

Apparaatfilters zijn cruciaal voor het aanvragen van toegang tot specifieke HID-apparaten. Wanneer uw webapplicatie navigator.hid.requestDevice() aanroept, toont de browser een apparaatkiezer, waarmee de gebruiker een apparaat kan selecteren. Met apparaatfilters kunt u de lijst met apparaten die aan de gebruiker worden gepresenteerd verkleinen, waardoor het voor hen gemakkelijker wordt om de juiste te vinden.

Een apparaatfilter is een JavaScript-object dat criteria specificeert voor het matchen van HID-apparaten. U kunt meerdere filters opgeven in de requestDevice() aanroep, en de browser zal alleen apparaten tonen die overeenkomen met ten minste één van de filters.

Eigenschappen van Apparaatfilters

• vendorId (optioneel): De USB Vendor ID van het apparaat. Dit is een 16-bits getal dat de fabrikant van het apparaat identificeert.
• productId (optioneel): De USB Product ID van het apparaat. Dit is een 16-bits getal dat het specifieke model van het apparaat identificeert.
• usagePage (optioneel): De HID Usage Page van het apparaat. Dit identificeert de categorie van het apparaat (bijv. Generic Desktop Controls, Game Controls).
• usage (optioneel): Het HID-gebruik van het apparaat. Dit identificeert de specifieke functie van het apparaat binnen de gebruikspagina (bijv. Joystick, Gamepad).

U kunt een combinatie van deze eigenschappen gebruiken om zeer specifieke filters te maken. U kunt bijvoorbeeld filteren op apparaten met een specifieke vendorId en productId om een bepaald model gamepad te targeten.

Praktische Voorbeelden van Apparaatfilters

Laten we enkele praktische voorbeelden bekijken van hoe u apparaatfilters in uw webapplicaties kunt gebruiken.

Voorbeeld 1: Filteren op een Specifieke Gamepad

Stel dat u een specifieke gamepad wilt targeten met een bekende vendorId en productId. U kunt het volgende filter gebruiken:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360 Controller
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Verwerk het/de geselecteerde appara(a)t(en)
  })
  .catch((error) => {
    // Behandel fouten
  });

            

              
                Copy
              
            
          

In dit voorbeeld zal het filter alleen apparaten matchen met een vendorId van 0x045e (Microsoft) en een productId van 0x028e (Xbox 360 Controller). Vervang deze door de juiste Vendor ID en Product ID van het apparaat dat u wilt targeten.

Voorbeeld 2: Filteren op Willekeurige Gamepads

Als u de gebruiker wilt toestaan elke gamepad te selecteren, kunt u een filter gebruiken dat de usagePage en usage voor gamepads specificeert:

            const filters = [
  {
    usagePage: 0x01, // Algemene Bureaubladbediening
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Verwerk het/de geselecteerde appara(a)t(en)
  })
  .catch((error) => {
    // Behandel fouten
  });

            

              
                Copy
              
            
          

Dit filter zal elk HID-apparaat matchen dat zichzelf identificeert als een gamepad met behulp van de standaard HID-gebruikscodes.

Voorbeeld 3: Filters Combineren

U kunt meerdere filters combineren voor meer flexibiliteit. U kunt bijvoorbeeld de gebruiker de keuze geven tussen een specifiek gamepadmodel of een willekeurige gamepad:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360 Controller
  },
  {
    usagePage: 0x01, // Algemene Bureaubladbediening
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Verwerk het/de geselecteerde appara(a)t(en)
  })
  .catch((error) => {
    // Behandel fouten
  });

            

              
                Copy
              
            
          

In dit geval toont de apparaatkiezer zowel de specifieke Xbox 360 Controller (indien aangesloten) als elk ander apparaat dat zichzelf als een gamepad identificeert.

Voorbeeld 4: Filteren op een specifiek toetsenbordtype op een systeem

Sommige niche-toetsenborden vereisen specifieke HID-codes om correct te initialiseren. Het volgende voorbeeld gaat ervan uit dat u de vendor ID, product ID, usage page en het gebruik voor het toetsenbord kent. U kunt deze informatie meestal vinden in de documentatie van de fabrikant, of met behulp van tools voor het weergeven van apparaten die op de meeste besturingssystemen beschikbaar zijn.

            const filters = [
    {
        vendorId: 0x1234,  // Vervang door uw vendor ID
        productId: 0x5678, // Vervang door uw product ID
        usagePage: 0x07,   // Vervang door uw usage page (bijv. Keyboard/Keypad)
        usage: 0x01      // Vervang door uw usage (bijv. Keyboard)
    }
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Verwerk het/de geselecteerde appara(a)t(en)
  })
  .catch((error) => {
    // Behandel fouten
  });

            

              
                Copy
              
            
          

Apparaatinformatie Ophalen

Zodra de gebruiker een apparaat heeft geselecteerd, kunt u de informatie ervan openen met het HIDDevice-object.

Eigenschappen van HIDDevice

• vendorId: De USB Vendor ID van het apparaat.
• productId: De USB Product ID van het apparaat.
• productName: De naam van het apparaat.
• collections: Een array van HIDCollection-objecten die de HID-rapportdescriptors van het apparaat vertegenwoordigen.

U kunt deze informatie gebruiken om het apparaat te identificeren en uw applicatie dienovereenkomstig te configureren.

HID-rapporten Verwerken

Nadat u een HIDDevice hebt verkregen, moet u het openen en beginnen te luisteren naar HID-rapporten. HID-rapporten zijn de ruwe data die door het apparaat naar uw applicatie worden verzonden.

Het Apparaat Openen

            device.open()
  .then(() => {
    console.log('Apparaat geopend');

    // Begin met luisteren naar invoerrapporten
    device.addEventListener('inputreport', (event) => {
      const { data, reportId } = event;
      // Verwerk het invoerrapport
      console.log(`Invoerrapport met ID ${reportId} ontvangen:`, data);
    });
  })
  .catch((error) => {
    console.error('Kon apparaat niet openen:', error);
  });

            

              
                Copy
              
            
          

Invoerrapporten Verwerken

Invoerrapporten worden ontvangen als DataView-objecten. De structuur van de data hangt af van de HID-rapportdescriptor van het apparaat. U zult de documentatie van het apparaat moeten raadplegen om te begrijpen hoe u de data moet interpreteren.

Hier is een vereenvoudigd voorbeeld van hoe u een invoerrapport kunt verwerken:

            device.addEventListener('inputreport', (event) => {
  const { data, reportId } = event;

  // Aannemende dat de eerste byte van het rapport de knopstatus vertegenwoordigt
  const buttonState = data.getUint8(0);

  // Verwerk de knopstatus
  if (buttonState & 0x01) {
    console.log('Knop 1 ingedrukt');
  }
  if (buttonState & 0x02) {
    console.log('Knop 2 ingedrukt');
  }
});

            

              
                Copy
              
            
          

Dit is een zeer eenvoudig voorbeeld. Echte HID-apparaten hebben vaak complexere rapportstructuren. Het reverse-engineeren van het HID-rapport kan een complex proces zijn; er zijn echter tools beschikbaar die helpen bij het parseerproces.

Foutafhandeling

Het is belangrijk om fouten correct af te handelen wanneer u met WebHID werkt. Hier zijn enkele veelvoorkomende fouten die u kunt tegenkomen:

• SecurityError: De gebruiker heeft toestemming voor toegang tot HID-apparaten geweigerd.
• NotFoundError: Er zijn geen overeenkomende apparaten gevonden.
• InvalidStateError: Het apparaat is al geopend.
• Andere fouten: USB-fouten, onverwachte verbrekingen van de apparaatverbinding.

Plaats uw WebHID-code altijd in try...catch-blokken en geef informatieve foutmeldingen aan de gebruiker.

Best Practices voor WebHID-ontwikkeling

• Gebruik Apparaatfilters: Gebruik altijd apparaatfilters om de lijst met apparaten die aan de gebruiker worden getoond te verkleinen.
• Geef Duidelijke Instructies: Geef gebruikers instructies over hoe ze het apparaat moeten aansluiten en autoriseren. Als het apparaat niet verschijnt, leg dan uit waar ze Vendor ID's en Product ID's voor veelvoorkomende apparaten kunnen vinden.
• Handel Fouten Correct Af: Implementeer robuuste foutafhandeling voor een soepele gebruikerservaring.
• Raadpleeg Apparaatdocumentatie: Raadpleeg de documentatie van het apparaat om de HID-rapportdescriptor te begrijpen.
• Test op Meerdere Platformen: Test uw applicatie op verschillende browsers en besturingssystemen om compatibiliteit te garanderen.
• Denk aan Veiligheid: Wees u bewust van de veiligheidsimplicaties bij het werken met gebruikersinvoer. Sanitizeer data en vermijd het uitvoeren van niet-vertrouwde code.
• Bied Alternatieven: Als WebHID niet wordt ondersteund of de gebruiker toestemming weigert, bied dan alternatieve invoermethoden.

Geavanceerde Technieken

Feature Rapporten

Naast invoerrapporten kunnen HID-apparaten ook feature-rapporten verzenden en ontvangen. Feature-rapporten worden gebruikt om het apparaat te configureren of de status ervan op te vragen.

Om een feature-rapport te verzenden, gebruikt u de device.sendFeatureReport()-methode.

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Voorbeelddata

device.sendFeatureReport(reportId, data)
  .then(() => {
    console.log('Feature-rapport succesvol verzonden');
  })
  .catch((error) => {
    console.error('Verzenden van feature-rapport mislukt:', error);
  });

            

              
                Copy
              
            
          

Om een feature-rapport te ontvangen, gebruikt u de device.getFeatureReport()-methode.

            const reportId = 0x01;

device.getFeatureReport(reportId)
  .then((data) => {
    console.log('Feature-rapport ontvangen:', data);
  })
  .catch((error) => {
    console.error('Ophalen van feature-rapport mislukt:', error);
  });

            

              
                Copy
              
            
          

Output Rapporten

WebHID ondersteunt ook output-rapporten, waarmee u data *naar* het apparaat kunt sturen. U kunt bijvoorbeeld output-rapporten gebruiken om LED's of andere actuatoren op het apparaat te bedienen.

Om een output-rapport te verzenden, gebruikt u de device.sendReport()-methode.

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Voorbeelddata

device.sendReport(reportId, data)
  .then(() => {
    console.log('Output-rapport succesvol verzonden');
  })
  .catch((error) => {
    console.error('Verzenden van output-rapport mislukt:', error);
  });

            

              
                Copy
              
            
          

Veiligheidsoverwegingen

Toegang tot WebHID vereist toestemming van de gebruiker, wat helpt om sommige veiligheidsrisico's te beperken. Het is echter nog steeds belangrijk om u bewust te zijn van mogelijke kwetsbaarheden.

• Data Sanering: Sanitizeer altijd data die van HID-apparaten wordt ontvangen om code-injectie of andere aanvallen te voorkomen.
• Oorsprongsbeperkingen: WebHID is onderworpen aan het same-origin-beleid, wat cross-origin toegang tot HID-apparaten voorkomt.
• Gebruikersbewustzijn: Informeer gebruikers over de risico's van het verlenen van toegang tot HID-apparaten en moedig hen aan om alleen toestemming te geven aan vertrouwde websites.

Globale Perspectieven en Voorbeelden

De WebHID API heeft wereldwijde implicaties, waardoor ontwikkelaars webapplicaties kunnen maken die een breed scala aan apparaten van verschillende fabrikanten en regio's ondersteunen. Denk aan deze voorbeelden:

• Gaming: Ondersteuning van gamepads van diverse fabrikanten uit verschillende landen (bijv. Sony PlayStation-controllers, Microsoft Xbox-controllers, Nintendo Switch Pro Controller, en minder bekende merken uit Azië en Europa).
• Toegankelijkheid: Het creëren van aangepaste invoerapparaten voor gebruikers met een beperking, rekening houdend met verschillende regionale toegankelijkheidsnormen en voorkeuren. Bijvoorbeeld, gespecialiseerde toetsenborden of schakelinterfaces ontworpen voor specifieke behoeften en beschikbaar in verschillende lay-outs.
• Industriële Automatisering: Koppelen met industriële controllers en sensoren die worden gebruikt in productiefaciliteiten over de hele wereld, met ondersteuning voor verschillende communicatieprotocollen en dataformaten.
• Wetenschappelijk Onderzoek: Verbinden met wetenschappelijke instrumenten die wereldwijd in onderzoekslaboratoria worden gebruikt, zodat onderzoekers data rechtstreeks in webapplicaties kunnen verzamelen en analyseren. Stelt u zich voor dat u laboratoriumapparatuur in een universiteit in Tokio bestuurt vanaf de laptop van een onderzoeker in Londen.
• Onderwijs: Ondersteuning van educatieve robots en interactieve apparaten die wereldwijd in klaslokalen worden gebruikt, waardoor studenten praktische leerervaringen krijgen. Dit kan bijvoorbeeld codeerrobots omvatten die in China zijn vervaardigd en in een klaslokaal in Brazilië worden gebruikt.

WebHID vs. Andere Web-API's

Het is de moeite waard om te bekijken hoe WebHID zich verhoudt tot andere web-API's die te maken hebben met apparaatinteractie:

• Gamepad API: De Gamepad API biedt een interface op een hoger niveau, specifiek voor gamepads. WebHID biedt meer flexibiliteit en controle, maar vereist meer handmatige verwerking van apparaatdata. De Gamepad API is zeer geschikt voor gangbare gamepads, terwijl WebHID meer exotische of gespecialiseerde invoerapparaten kan ondersteunen.
• WebUSB API: WebUSB stelt webapplicaties in staat om rechtstreeks met USB-apparaten te communiceren. WebHID is specifiek ontworpen voor Human Interface Devices, terwijl WebUSB kan worden gebruikt voor een breder scala aan USB-apparaten. WebUSB kan worden gebruikt voor een gespecialiseerd wetenschappelijk instrument dat via USB is aangesloten, terwijl WebHID zou worden gebruikt voor een aangepast toetsenbord of muis.
• Web Serial API: Web Serial maakt communicatie via seriële poorten mogelijk. Dit is handig voor interactie met ingebedde systemen en andere apparaten die via seriële verbindingen communiceren. Een microcontroller die data verzendt via een seriële verbinding zou Web Serial kunnen gebruiken, terwijl een op maat gemaakte joystick WebHID zou gebruiken.

De Toekomst van WebHID

De WebHID API evolueert voortdurend, met doorlopende inspanningen om de veiligheid, prestaties en gebruiksgemak te verbeteren. Naarmate meer apparaten de HID-standaard overnemen, zal WebHID een steeds belangrijker hulpmiddel worden voor webontwikkelaars. Verwacht in de toekomst meer geavanceerde functies en verbeterde browserondersteuning.

Conclusie

WebHID is een krachtige API die een breed scala aan mogelijkheden voor webapplicaties opent. Door apparaatfilters te begrijpen en te weten hoe u HID-rapporten moet verwerken, kunt u boeiende en interactieve webervaringen creëren die het volledige potentieel van Human Interface Devices benutten. Of u nu een game, een toegankelijkheidstool of een industrieel besturingssysteem bouwt, WebHID kan u helpen uw webapplicatie te verbinden met de fysieke wereld. Vergeet niet om prioriteit te geven aan gebruikerservaring, veiligheid en platformonafhankelijke compatibiliteit om succesvolle en wereldwijd toegankelijke WebHID-applicaties te creëren.